/*
 * Copyright (c) 2011 Sapienza University of Rome.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * - Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the
 *   distribution.
 * - Neither the name of the Sapienza University of Rome nor the names of
 *   its contributors may be used to endorse or promote products derived
 *   from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL SAPIENZA
 * UNIVERSITY OF ROME OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * This interface is provided by the AdaptiveEngineC component. It is used to store input
 * values to the AdaptiveEngine (SP,TTR,TTRD) and to retrieve the DISSense schedule
 * parameters (GTI,RI,DCI and Skip).
 *
 * The AdaptiveLayer interface is used by the ManagerC and CtpRoutingEngineC components. The
 * former uses it to store newly computed input values (sink only) or to get schedule informations (both, sink and nodes).
 * The latter uses this interface to propagate output values over the Implicit Backward Channel (both, sink and nodes) or
 * to store fresh values from the Implicit Backward Channel (nodes only).
 *
 * @author Ugo Colesanti <colesanti@dis.uniroma1.it>
 * @version 1.01 (September 28, 2011)
 *
 */
interface AdaptiveLayer{

	/**
	 * Get the current Resynchronization Interval (RI). This function is used by the ManagerC component
	 * (for both Sink and Nodes) to set its schedule.
	 * @return The Resynchronization Interval in milliseconds.
	 */
	command uint16_t getCurrentRI() ;

	/**
	 * Get the current Data Collection Interval (DCI). This function is used by the ManagerC component
	 * (for both Sink and Nodes) to set its schedule. The function is also used by the CTPRoutingEngine
	 * to propagate the DCI value over the ImplicitBackwardChannel.
	 * @return The Data Collection Interval in milliseconds
	 */
	command uint16_t getCurrentDCI() ;

	/**
	 * Get the Skip parameter. This function is used by the ManagerC component
	 * (for both Sink and Nodes) to set its schedule. The function is also used by the CTPRoutingEngine
	 * to propagate the Skip value over the ImplicitBackwardChannel.
	 * @return The Skip parameter value
	 */
	command uint8_t getCurrentSkip() ;

	/**
	 * Get the Guard Time Interval (GTI). This function is used by the ManagerC component
	 * (for both Sink and Nodes) to set its schedule.
	 * @return The Guard Time Interval in milliseconds
	 */
	command uint16_t getCurrentGT() ;

	/**
	 * Store the length of the next scheduled Resynchronization Interval (RI).
	 * This function is called by the CtpRoutingEngine that implements the
	 * Implicit Backward Channel (IBC), thus, it is not called by the Sink. Furthermore,
	 * since the IBC is active during RI, DISSense cannot update the interval length directly,
	 * rather, it stores it for the next RI scheduled.
	 * @param nri The length, in milliseconds, of the next Resynchronization Interval
	 */
	command void storeNextRI(uint16_t nri) ;

	/**
	 * Store the length of the Data Collection Interval (DCI). This function is called by the CtpRoutingEngine that implements the
	 * Implicit Backward Channel (IBC), thus, it is not called by the Sink. Furthermore, differently from
	 * RI, the Data Collection Interval takes place after the Implicit Backward Channel,
	 * thus, the new value can be used just after this function is called.
	 * @param cdci The length, in milliseconds, of the Data Collection Interval
	 */
	command void storeCurrentDCI(uint16_t cdci) ;

	/**
	 * Store the new Skip parameter value. This function is called by the CtpRoutingEngine that implements the
	 * Implicit Backward Channel (IBC), thus, it is not called by the Sink. Furthermore, as for te DCI, the Skip value is directly used.
	 * @param sk The skip parameter value
	 */
	command void storeCurrentSkip(uint8_t sk) ;

	/**
	 * Store the new Sampling Period (SP). This function is called by the CtpRoutingEngine that implements the
	 * Implicit Backward Channel (IBC), thus, it is not called by the Sink. When stored, the value is directly used.
	 * @param csp The new sampling period in seconds.
	 */
	command void storeCurrentSamplingPeriod(uint16_t csp) ;

	/**
	 * Check if a RI is scheduled during the current Active Phase. This function is called by the ManagerC component
	 * (for both Sink and Node) to determine the next state in the schedule.
	 * @return TRUE if the RI is scheduled during the current Active Phase, FALSE otherwise.
	 */
	command bool isResyncScheduled() ;

	/**
	 * Get the length of the next Resynchronization Interval scheduled. This function is called by the
	 * CTPRoutingEngine component (for both, Sink and Node) to propagate the new value of the RI over the Implicit Backward Channel.
	 * @return The length, in milliseconds, of the next Resynchronization Interval scheduled.
	 */
	command uint16_t getNextRI() ;

	/**
	 * Initializes the AdaptiveEngine, the SINK must call it during the Boot.booted event
	 * and BEFORE any other invocations on the AdaptiveLayer interface.
	 * The Node calls it when it receives a synchronization message.
	 *
	 * @param ctr The number of schedules remaining before a RI takes place. (For sink is 0, for node is 1)
	 * @param ri_ub The RI length upper bound (in milliseconds)
	 * @param dci_ub The DCI length upper bound (in milliseconds)
	 * @param sp The Sampling period (in seconds)
	 * @param ri The actual RI length (in milliseconds)
	 * @param dci The actual DCI length (in milliseconds)
	 * @param sk The Skip parameter
	 *
	 * Other nodes may call it during the resynchronization phase (when a sync beacon is received)
	 */
	command void initialize(uint8_t ctr, uint16_t ri_ub, uint16_t dci_ub , uint16_t sp, uint16_t ri, uint16_t dci, uint8_t sk) ;

	/**
	 * Ask the component that uses the AdaptiveLayer to give new input values to the component.
	 *
	 */
	event void needInValuesUpdate() ;

	/**
	 * Update the input values. Must be called by the ManagerC component witin a needInValuesUpdate() event.
	 * @param ttr The Time To Resynchronize (in milliseconds) computed by the ManagerC component
	 * @param ttrd The Time To Receive Data (in milliseconds) computed by the ManagerC component
	 * @param sp The new Sampling Period (in seconds)
	 */
	command void updateInValues(uint16_t ttr, uint16_t ttrd, uint16_t sp) ;

	/**
	 * Must be called by the ManagerC component at the beginning of the new Active Phase BEFORE
	 * other invocations on the AdaptiveLayer interface.
	 *
	 */
	command void activePeriodBegin() ;


}
